home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / t3_1 / doc.lha / documentation / manual / library.mss < prev    next >
Text File  |  1987-06-30  |  13KB  |  329 lines
  1. @part[LIBRARY, root "TMAN.MSS"]        @Comment{-*-System:TMAN-*-}
  2. @appendix[Libraries]
  3. @label[LibrariesAppendix]
  4.  
  5. This appendix describes various software packages which are not
  6. officially part of the @Tau[] language but which are of general utility.
  7. Some are available within the implementations (@timp[])
  8. directly, while others must be loaded from external files
  9. using @tc[LOAD].
  10.  
  11. @dc{ Etc.
  12. Talk about the various temporary hacks to get around various implementation
  13. inadequacies.
  14. }
  15.  
  16. @dc{ What things should be here described?  Refer somewhere to the Yale
  17. looping constructs?  What about DEFINE-APOLLO etc.?
  18. What about the apollo system utilities?
  19. What about @tc[MSG] and the TLISP utilities?
  20. }
  21.  
  22. @section[The data base]
  23.  
  24. The @iix[data base] is a global two-dimensional sparse
  25. table indexed by arbitrary objects.  Entries to the data base can be
  26. added, retrieved, and deleted via the system procedures
  27. @tc[PROPERTY] and @tc[REMOVE-PROPERTY].
  28.  
  29. By being a global resource, the data base violates a basic tenet of the
  30. @Tau[] design philosophy, that the system should have no global resources.
  31. Global resources present modularity problems, because different programs
  32. may make conflicting use of them.  In the case of the data base, program
  33. A might make use of data base entries whose second coordinate is the
  34. symbol @tc[FOO].  If program B also makes use of such data base entries,
  35. but does not know (or want to know) that program A is already making
  36. use of those entries, then each program may write over or be confused by
  37. the other's entries.
  38.  
  39. The data base corresponds to what is known in other Lisp dialects
  40. as @qu"property lists."
  41.  
  42. @info[NOTES="Settable"]
  43. @descN[
  44. F1="(PROPERTY @i[object1 object2]) @yl[] @i[object]", FN1="PROPERTY",
  45. F2="(GET @i[object1 object2]) @yl[] @i[object]", FN2="GET"
  46. ]
  47. Access the data base entry indexed by @i[object1] and @i[object2].
  48.   @begin[ProgramExample]
  49. (SET (PROPERTY 'FOO 'COLOR) 'RED)    @ev[]  RED
  50. (PROPERTY 'FOO 'COLOR)             @ev[]  RED
  51. (SET (PROPERTY 'FOO 'COLOR) 'GREEN)  @ev[]  GREEN
  52. (PROPERTY 'FOO 'COLOR)             @ev[]  GREEN
  53.   @end[ProgramExample]
  54.     @BeginInset[Bug:]
  55.     In @Timp[] 2.7, @i[object1] must be a symbol.
  56.     @EndInset[]
  57. @EndDescN[]
  58.  
  59. @info[EQUIV="PUTPROP"]
  60. @descN[
  61. F1="(SET-PROPERTY @i[object1 object2 value]) @yl[] @i[value]",
  62. FN1="SET-PROPERTY",
  63. F2="(PUT @i[object1 object2 value]) @yl[] @i[value]", FN2="PUT"
  64. ]
  65. Sets the data base entry indexed by @i[object1] and @i[object2].
  66.   @begin[ProgramExample]
  67. (SET-PROPERTY @i[object1 object2 value])
  68.   @ce[]  (SET (PROPERTY @i[object1 object2]) @i[value])
  69.   @end[ProgramExample]
  70.     @BeginInset[Bug:]
  71.     In @Timp[] 2.7, @i[object1] must be a symbol.
  72.     @EndInset[]
  73. @EndDescN[]
  74.  
  75. @desc[(REMOVE-PROPERTY @i[object1 object2]) @yl[] @i[object] @r[or] @i[false]]
  76. @tc[REMOVE-PROPERTY] removes the data base entry indexed by @i[object1]
  77. and @i[object2].
  78. It returns false if there was no such entry.
  79. (Note that there is no way to distinguish the absence of an entry from
  80. an entry whose value is false.)
  81. @EndDesc[REMOVE-PROPERTY]
  82.  
  83. @section[Symbol tables]
  84.  
  85. @dc{ Talk about internedness, etc.  Maybe this section should be flushed?
  86. ... pretty random. }
  87.  
  88. @desc[(MAKE-SYMBOL @i[string]) @yl[] @i[symbol]]
  89. Returns a new symbol whose print name is @i[string].
  90. @EndDesc[MAKE-SYMBOL]
  91.  
  92. A @iixs[symbol table] maps strings to symbols.
  93.  
  94. @info[EQUIV="OBARRAY"]
  95. @desc[*THE-SYMBOL-TABLE*]
  96. This variable holds the value of the standard system symbol table.
  97. This is used implicitly by @tc[STRING->SYMBOL] and @tc[READ].
  98. @EndDesc[*THE-SYMBOL-TABLE*]
  99.  
  100. @desc[(MAKE-SYMBOL-TABLE @i[size]) @yl[] @i[symbol-table]]
  101. Creates a new symbol table, suitable as argument to
  102. @tc[INTERN] and other symbol-table manipulation routines.
  103. @EndDesc[MAKE-SYMBOL-TABLE]
  104.  
  105. @desc[(INTERN @i[string symbol-table]) @yl[] @i[symbol]]
  106. Looks in @i[symbol-table] for a symbol whose print name
  107. is @tc[STRING-EQUAL?] to @i[string], and returns it if one exists.
  108. If not, it creates a new symbol, whose print name is a copy of @i[string],
  109. and returns it.
  110. @EndDesc[INTERN]
  111.  
  112. @desc[(REALLY-INTERN @i[string symbol-table]) @yl[] @i[symbol]]
  113. Similar to @tc[INTERN], except that if a
  114. new symbol must be created, @i[string] itself is used as the print name,
  115. not a copy of @i[string].
  116. @EndDesc[REALLY-INTERN]
  117.  
  118. @desc[(INTERNED @i[string symbol-table]) @yl[] @i[symbol] @r[or] @i[false]]
  119. Looks in @i[symbol-table] for a symbol whose print name
  120. is @tc[STRING-EQUAL?] to @i[string].  Returns it if one exists,
  121. returns false otherwise.
  122. @EndDesc[INTERNED]
  123.  
  124. @desc[(INTERNED? @i[string symbol-table]) @yl[] @i[boolean]]
  125.   @begin[ProgramExample]
  126. (INTERNED? @i[string symbol-table])
  127.   @ce[]
  128. (TRUE? (INTERNED @i[string symbol-table]))
  129.   @end[ProgramExample]
  130. @EndDescN[INTERNED?]
  131.  
  132. @info[EQUIV="MAPATOMS"]
  133. @desc[(WALK-SYMBOL-TABLE @i[procedure symbol-table]) @yl[] @i[undefined]]
  134. @i[Procedure] is called on each symbol in @i[symbol-table].
  135. @EndDesc[WALK-SYMBOL-TABLE]
  136.  
  137.  
  138. @section[List utilities]
  139.  
  140. @dc{ Move all that random stuff here from the list chapter. }
  141.  
  142. @desc[@el[](MEM @i[predicate object list]) @yl[] @i[list]]
  143. Returns the first @i[tail] of @i[list] such that
  144. @tc[(@i[predicate object] (CAR @i[tail]))].
  145. @begin[programExample]
  146. (MEM EQ? 'A '(B A D E))  @ev[]  (A D E)
  147. @end[ProgramExample]
  148. @EndDesc[MEM]
  149.  
  150. @desc[(MEMQ @i[object list]) @yl[] @i[list]]
  151. @begin[ProgramExample]
  152. (MEMQ @i[object list])  @ce[]  (MEM EQ? @i[object list])
  153. @end[ProgramExample]
  154. @EndDesc[MEMQ]
  155.  
  156. @dc{ MEMV, MEMV?, ... }
  157.  
  158. @desc[@el[](ANY @i[predicate . lists]) @yl[] @i[object]]
  159. Calls the @i[predicate] on successive elements of the @i[lists],
  160. stopping as soon as the @i[predicate] returns a value other than false.
  161. This value is returned as @tc[ANY]'s value.
  162. @begin[ProgramExample]
  163. (ANY NUMBER? '(A B 3 FOO))  @ev[]  @r[true]
  164. (ANY NUMBER? '(A B C FOO))  @ev[]  @r[false]
  165. (ANY < '(1 2 3) '(6 6 6))   @ev[]  @r[true]
  166. (ANY MEMQ '(A B C) '((X B) (U B Z) (C D E F)))  @ev[]  (B Z)
  167. @end[ProgramExample]
  168. @dc{that last is a horrible example!...}
  169. @EndDesc[ANY]
  170.  
  171. @info[EQUIV="SOME"]
  172. @desc[(ANYCDR @i[predicate . lists]) @yl[] @i[object]]
  173. Like @tc[ANY], but the @i[predicate] is called on successive
  174. tails of the @i[lists] instead of successive elements.
  175. @EndDesc[ANYCDR]
  176.  
  177. @desc[@el[](EVERY @i[predicate . lists]) @yl[] @i[object]]
  178. Calls the @i[predicate] on successive elements of the @i[lists],
  179. stopping as soon as the @i[predicate] returns false.
  180. If for every element @i[predicate] returns true, @tc[EVERY]
  181. returns the value of the last call.
  182. @begin[ProgramExample]
  183. (EVERY NUMBER? '(1 2 3 -15.7))  @ev[]  @r[true]
  184. (EVERY NUMBER? '(1 2 3 FOO))    @ev[]  @r[false]
  185. (EVERY ASSQ '(A B C)        @dc{ This is why people hate Lisp. }
  186.      '(((A X) (X Y)) ((A J) (B K)) ((C D) (T U))))
  187.   @ev[]  (C D)
  188. @end[ProgramExample]
  189. @EndDesc[EVERY]
  190.  
  191. @desc[(EVERYCDR @i[predicate . lists]) @yl[] @i[object]]
  192. Like @tc[EVERY], but the @i[predicate] is called on successive
  193. tails of the @i[lists] instead of successive elements.
  194. @EndDesc[EVERYCDR]
  195.  
  196. @desc[(EVERYCDR? @i[predicate . lists]) @yl[] @i[boolean]]
  197. @begin[ProgramExample]
  198. (EVERYCDR? @i[predicate . lists])  @ce[]  (TRUE? (EVERYCDR @i[predicate . lists]))
  199. @end[ProgramExample]
  200. @EndDesc[EVERYCDR?]
  201.  
  202. @desc[(ANYCDR? @i[predicate . lists]) @yl[] @i[boolean]]
  203. @begin[ProgramExample]
  204. (ANYCDR? @i[predicate . lists])  @ce[]  (TRUE? (ANYCDR @i[predicate . lists]))
  205. @end[ProgramExample]
  206. @EndDesc[ANYCDR?]
  207.  
  208. @desc[(POS @i[predicate object list]) @yl[] @i[integer] @r[or] @i[false]]
  209. Returns the position of the first item in @i[list] such that
  210. @tc[(@i[predicate object item])], or false if there is no such
  211. item.
  212. @EndDesc[POS]
  213.  
  214. @desc[(POSQ @i[object list]) @yl[] @i[integer] @r[or] @i[false]]
  215. @dc{ Randomness. }
  216. @begin[ProgramExample]
  217. (POSQ @i[object list])  @ce[]  (POS EQ? @i[object list])
  218. @end[ProgramExample]
  219. @EndDesc[POSQ]
  220.  
  221. @desc[(APPEND-REVERSE @i[list ending]) @yl[] @i[list]]
  222. @begin[ProgramExample]
  223. (APPEND-REVERSE @i[list ending])  @ce[]
  224.   (APPEND (REVERSE @i[list]) @i[ending])
  225.  
  226. (APPEND-REVERSE '(A B C) '(D E))  @ev[]  (C B A D E)
  227. @end[ProgramExample]
  228. @EndDesc[APPEND-REVERSE]
  229.  
  230. @info[EQUIV="NRECONC"]
  231. @desc[(APPEND-REVERSE! @i[list ending]) @yl[] @i[list]]
  232.   @begin[ProgramExample]
  233. (APPEND-REVERSE! @i[list ending])  @ce[]
  234. (APPEND! (REVERSE! @i[list]) @i[ending])
  235.   @end[ProgramExample]
  236. @EndDesc[APPEND-REVERSE!]
  237.  
  238. @begin[comment]                
  239. @desc[(DELETE @i[object list]) @yl[] @i[list]]
  240. @ProgramExample[(DELETE @i[object list])  @ce[]  (DEL ALIKEV? @i[object list])]
  241. @EndDesc[DELETE]
  242.  
  243. @desc[(DELETE! @i[object list]) @yl[] @i[list]]
  244. Destructive version of @tc[DELETE].
  245. @EndDesc[DELETE!]
  246. @end[comment]
  247.  
  248. @section[Type-specific arithmetic]
  249.  
  250. A @iixs[fixnum] is an integer whose magnitude lies within an
  251. implementation-dependent range.  This range is guaranteed to include all
  252. integers which are acceptable as array, string, or vector indices.
  253. In @Timp[], this range is the half-open interval
  254. @w<[2@+[-28],2@+[28])>.
  255.  
  256. @info[NOTES="Type predicate"]
  257. @desc[(FIXNUM? @i[object]) @yl[] @i[boolean]]
  258. Returns true if @i[object] is a fixnum.
  259. @enddesc[FIXNUM?]
  260.  
  261. @desc[*MAX-FIXNUM* @yl[] @i[integer]]
  262. Returns the largest integer value within the fixnum range.  No integer
  263. answering true to @tc[FIXNUM?] is greater than @tc[*MAX-FIXNUM*].
  264. @enddesc[*MAX-FIXNUM*]
  265.  
  266. @desc[*MIN-FIXNUM* @yl[] @i[integer]]
  267. Returns the smallest integer value within the fixnum range.  No integer
  268. answering true to @tc[FIXNUM?] is less than @tc[*MIN-FIXNUM*].
  269.   @begin[ProgramExample]
  270. (FIXNUM? @i[x])
  271. @ce[]  (AND (INTEGER? X) (>= @i[x] *MIN-FIXNUM*) (<= @i[x] *MAX-FIXNUM*))
  272.   @end[ProgramExample]
  273. @enddesc[*MIN-FIXNUM*]
  274.  
  275. @label[FLONUM-ADD]    @Comment{ref: numbers chapter}
  276. The following procedures are defined for performing type-restricted
  277. arithmetic.  These procedures should be considered specializations of
  278. their corresponding generic arithmetic procedures.  They assume
  279. restrictions on the types of their arguments and results.  The prefix
  280. @tc[FX] means @qu"fixnum-specific," and @tc[FL] means
  281. @qu"flonum-specific."  For example,
  282.   @begin[ProgramExample, LongLines Keep]
  283. (FX+ @i[x] @i[y])  @~
  284. @ce[]  (PROCLAIM FIXNUM? (+ (PROCLAIM FIXNUM? @i[x]) (PROCLAIM FIXNUM? @i[y])))
  285.   @end[ProgramExample]
  286. @Timp[] will implement calls to these type-specific procedures in a more
  287. efficient manner than calls to the corresponding generic procedures.
  288.  
  289. The following list catalogs the available routines.  In most case the
  290. effect of the procedure should be analogous to the example above.  The
  291. one exception is @tc[FX/], which is a specialization of the truncated
  292. (integer) division routine @tc[DIV], not of the division routine @tc[/].
  293.   @begin[ProgramExample]
  294. (FX+ @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FX+]
  295. (FL+ @i[fixnum1 fixnum2]) @yl[] @i[flonum]@tindex[FL+]
  296. (FX- @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FX-]
  297. (FL- @i[flonum1 flonum2]) @yl[] @i[flonum]@tindex[FL-]
  298. (FX* @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FX*]
  299. (FL* @i[fixnum1 fixnum2]) @yl[] @i[flonum]@tindex[FL*]
  300. (FX/ @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FX/]
  301. (FL/ @i[flonum1 flonum2]) @yl[] @i[flonum]@tindex[FL/]
  302. (FX= @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FX=]
  303. (FL= @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FL=]
  304. (FX< @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FX<]
  305. (FL< @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FL<]
  306. (FX> @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FX>]
  307. (FL> @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FL>]
  308. (FXN= @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FXN=]
  309. (FLN= @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FLN=]
  310. (FX>= @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FX>=]
  311. (FL>= @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FL>=]
  312. (FX<= @i[fixnum1 fixnum2]) @yl[] @i[boolean]@tindex[FX<=]
  313. (FL<= @i[flonum1 flonum2]) @yl[] @i[boolean]@tindex[FL<=]
  314. (FIXNUM-REMAINDER @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FIXNUM-REMAINDER]
  315. (FIXNUM-ODD? @i[fixnum]) @yl[] @i[boolean]@tindex[FIXNUM-ODD?]
  316. (FIXNUM-EVEN? @i[fixnum]) @yl[] @i[boolean]@tindex[FIXNUM-EVEN?]
  317. (FIXNUM-ABS @i[fixnum]) @yl[] @i[fixnum]@tindex[FIXNUM-ABS]
  318. (FIXNUM-MIN @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FIXNUM-MIN]
  319. (FIXNUM-MAX @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FIXNUM-MAX]
  320. (FIXNUM-LOGAND @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FIXNUM-LOGAND]
  321. (FIXNUM-LOGIOR @i[fixnum1 fixnum2]) @yl[] @i[fixnum]@tindex[FIXNUM-LOGIOR]
  322. (FIXNUM-LOGNOT @i[fixnum]) @yl[] @i[fixnum]@tindex[FIXNUM-LOGNOT]
  323. (FIXNUM-ASHR @i[fixnum]) @yl[] @i[fixnum]@tindex[FIXNUM-ASHR]
  324. (FIXNUM-ASHL @i[fixnum]) @yl[] @i[fixnum]@tindex[FIXNUM-ASHL]
  325. (FIXNUM->FLONUM @i[fixnum]) @yl[] @i[flonum]@tindex[FIXNUM->FLONUM]
  326. (FLONUM->FIXNUM @i[flonum]) @yl[] @i[fixnum]@tindex[FLONUM->FIXNUM]
  327.  
  328.   @end[ProgramExample]
  329.